can you please add the jsdocs to documents the meaning of minInterval? It's important to stress that this should be the minimum interval available between data. If for example we are visualizing yearly data from 2016 to 2019 and we the consumer compute the first interval an error will occur: 2016 is a leap year this the interval is greater then the minComputedInterval of 365 days.

For a datum with monthly aggregation they should provide 28 days as the minInterval.
It's worth also having a look at the current data_histogram intervals https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html because with time intervals there is always a distinction between calendar intervals and fixed intervals.

I would also suggest to check if there is a better way to specify that interval. In particular, for Time domains.
I'd like to avoid pushing the consumer to compute that minInterval in millis manually and rather accept also some data_histogram intervals values like 1D or 1M or similar. This facilitate the use of the library and enables the consumer to just specify a simple interval.
Keep also an eye on this deprecation: elastic/kibana#27410

@markov00

See comment explaining minInterval with warnings about certain kinds of timeseries intervals here: 9de618a

It would certainly be possible to extend the type of minInterval to accept either a raw number which would match the same units as the raw datum or a shorthand for intervals specific to a certain unit that we internally use to compute the actual minInterval of a domain. We could do something like:

interface DomainMinInterval {
  minInterval?: number | TimeInterval;
}

And then TimeInterval could be defined either as just a string that we parse ourselves or an interface with explicit unit: string and length: number where valid units are restricted to a certain set of strings.

However, this seems to potentially duplicate efforts because on the Kibana side, we are already using @elastic/datemath and parseInterval (note that parseInterval is not a part of @elastic/datemath and is instead a function defined within Kibana) to transform the returned interval from Elasticsearch (a separate issue is that it seems the Discover query still uses the deprecated interval field instead of calendar_interval or fixed_interval). That is, in the Discover data, we get back chartData.ordered.interval which is a moment duration which requires no additional parsing or transformation and is passed directly in as the value of minInterval:

    // Note: this is using the deprecated `interval` field; see above
    const xInterval = chartData.ordered.interval; 

    const xDomain = {
      domainRange: {
        min: domainMin,
        max: domainMax,
      },
      minInterval: xInterval,
    };

So for developer users of elastic-charts in Kibana, they should already have the ability to directly pass in correctly formatted custom minInterval values given the tools that exist within Kibana.

If we want to support more custom time interval shorthands within elastic-charts itself, that seems to me to be an additional enhancement to consider outside of this PR (the functionality exposed by this PR is needed for the Discover replacement, which does not need support for interval shorthands; and any other app within Kibana should be able to use the parseInterval helper to get the milliseconds value) because we may want to consider how to avoid duplication of efforts between our own internal parser and Kibana's. (One small difference that may be an issue is that Kibana is using moment while elastic-charts using luxon which uses slightly different strings to define patterns.)

Thanks @emmacunningham for the clarification. Yes let's keep it like it is for the moment